/*
 * ProtocolHandler.java    0.0.1    17/set/2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */ 
package org.mentalsmash.tazio.net.cs.server;

import java.nio.ByteBuffer;

import org.mentalsmash.tazio.net.cs.server.impl.ChannelFacade;

/**
 * This interface should be implemented by tazio's components who wish to manage messages from clients.
 * Several methods such as <code>starting()</code>, <code>started()</code>, etc... are provided to notify 
 * of successfully handled connections
 * <p>
 * This class and all the classes in this package are largely inspired to the presentation
 * "How To Build A Scalable NIO Server, Mark II" by Ron Hitchens (http://ronsoft.com)
 * </p>
 * @version    0.0.1 17/set/2009
 * @author     Andrea Reale <andrea.reale@gmail.com>
 */
public interface ProtocolHandler {
	

	/**
	 * This method is automatically called by the working thread managing the readiness event for 
	 * the channel associated with this handler when new input is ready on the channel's queue. Since
	 * the IO is nonblocking the presence of some input does not mean that a complete message has arrived:
	 * therefore this method has the role to detect a complete application message and in such a case 
	 * drain the channel's input queue  and return it as a ByteBuffers.
	 * In the case no complete message is detected the source's input queue should be left as it is, and
	 * <code>null</code> should be returned
	 * @param source The channel that has ready input in its queue
	 * @return a byte buffer containing a complete application message.
	 */
	public ByteBuffer nextMessage(ChannelFacade source);
	
	/**
	 * This method is automatically invoked by the working thread managing the readiness event for the
	 * channel associated with this handler, when a complete application message is dectected.
	 * The detected message is passed in the ByteBuffer argument.
	 * @param message The complete application message to be handled
	 * @param source The channel that originated the message
	 */
	public void handleMessage(ByteBuffer message, ChannelFacade source);
	
	/**
	 * This method is invoked when the handler is registered with a new source
	 * @param source the input channel the handler is attached to
	 */
	public void registered(ChannelFacade source);
	
	/**
	 * This method is invoked when the handler is unregisterd from a source (e.g. when the channel
	 * closes or disconnects). Notice that this method may not run in the same thread that handles messages,
	 * so care must be taken since this could be invoked why a message is being handled.
	 * @param source the channel attached to this handler
	 */
	public void unregistered(ChannelFacade source);
	
	
}
